Inside Macintosh: QuickDraw GX Objects /

Chapter 6 - Transform Objects / About Transform Objects

Transform Object Properties

The interface to transform objects is entirely procedural. You manipulate the information in a transform object by modifying its properties using QuickDraw GX functions.

Transform objects have six accessible properties, as shown in Figure 6-1. Note that, because a transform is an object and not a data structure, the order of the properties shown in Figure 6-1 is completely arbitrary. Properties in italics are references to other objects.

Figure 6-1 The transform object and its properties

These are the six accessible properties in a transform object:

• Clip. A reference to a specialized shape geometry that defines the visible area of the shape associated with this transform object. Only the parts of the shape that overlap with the clip remain visible when the shape is drawn. The transform clip is further described in the next section, "Clip."
• Mapping. A mathematical matrix that specifies the translation, scaling, rotation, skewing, and perspective of the shape associated with this transform object. The transform mapping is further described in the section "Mapping" on page 6-10.
• View port list. An array of references to the view ports that the shape associated with this transform object can be drawn to. The view port list is further described in the section "View Port List" on page 6-11.
• Hit-test parameters. Two values that provide criteria for hit-testing the shape associated with this transform object. The hit-test parameters specify what parts of the shape are to be tested for, and how close to a part a hit point must be to be considered successful. The hit-test parameters are further described in the section "Hit-Test Parameters" on page 6-11.
• Owner count. The number of existing references to this transform object. General information about owner counts is in the chapter "Introduction to QuickDraw GX" in this book; the section "Copying, Comparing, and Cloning Transform Objects" beginning on page 6-16 describes when and how to examine and alter a transform object's owner count.
• Tag list. A list of references to custom information about this transform object, stored in private data structures called tag objects. The chapter "Tag Objects" in this book describes tag objects in general and how you can use them to add custom information to objects.

QuickDraw GX provides functions to manipulate each of these transform object properties.

Clip

The clip property of a transform object is a specialized shape geometry that functions as a mask to restrict the visibility of a shape when it is displayed or printed. The clip shape is equivalent to a primitive shape, a shape (of any type) whose geometry and fill properties by themselves define the shape. In other words, a primitive shape does not use any information from a style object or transform object to determine its location, dimension, or even pen thickness; all dimensional information about a primitive shape is in the shape object itself.

The filled or framed parts of a transform's clip define the areas in which the shape attached to that transform show through. Figure 6-2 shows the effect of using a transform object to clip a shape representing a vase. The vase shape references a transform object whose clip property defines a clip shape consisting of four filled paths. Only the parts of the vase that intersect the filled paths are allowed to show through.

Figure 6-2 A transform clip

If the clip were a framed path shape instead of the filled path shape shown in Figure 6-2, only the parts of a shape that intersect the frame itself would be visible. And because the pen width is 0 for a primitive shape, the frame would be of hairline width only; the parts of the shape both outside and inside the hairline frame would be clipped out, as shown in Figure 6-3.

Figure 6-3 A framed transform clip

To use a framed shape with nonzero pen width as a clip shape, you first convert it to a primitive shape, at which point it becomes a filled shape in which the filled areas correspond to the pen width in the original framed shape. Figure 6-4 shows an example of converting a framed shape with a nonzero pen width into a transform clip shape.

Figure 6-4 Converting a framed shape with a nonzero pen width into a transform clip

You can use a bitmap shape as a clip, but only if its pixel depth is 1--meaning that each pixel has a value of 0 or 1--and if its color profile is nil. When a transform clip is a bitmap, its individual pixels mask the shape that is drawn. A pixel with a value of 1 allows the shape geometry to show through the area covered by that pixel, and a pixel with a value of 0 clips out the part of the shape covered by that pixel. Figure 6-4 shows an example.

Figure 6-5 Using a bitmap as a transform clip

For more information on bitmap shapes, see the bitmap shapes chapter of Inside Macintosh: QuickDraw GX Graphics. For more information on primitive shapes, see
the geometric operations chapter of Inside Macintosh: QuickDraw GX Graphics.

QuickDraw GX provides functions that allow you to modify a transform clip by performing constructive geometry operations--such as union and intersection--between it and another shape. With these operations you can build a clip from one or more shapes. For example, you can start with the default clip shape, gxFullShape, which allows everything to show through, and use constructive geometry operations to restrict the visibility. Or you can start with an empty shape, gxEmptyShape, and use constructive geometry operations to increase visibility. Figure 6-6 shows one example (using reverse difference); the section "Getting, Setting, and Modifying the Transform Clip" beginning on page 6-20 describes the operations you can perform and the QuickDraw GX functions you use to modify a transform clip.

Figure 6-6 Modifying a transform clip by subtracting it from another shape

Mapping

The mapping property is a 3 3 matrix that specifies one or more transformations that
a transform object performs on its associated shape. It is the transforming aspect of
the mapping property that gives the transform object its name. You can use the transform mapping to perform the following operations on a shape:

• translation, which changes the position of the shape
• scaling, which shrinks or enlarges the shape horizontally or vertically or both
• rotation, which turns the shape about a fixed point
• skewing, which distorts the shape progressively along a single axis
• perspective, which distorts the shape to provide a three-dimensional appearance

Figure 6-7 shows examples of some of these transformations.

Figure 6-7 Effects of the transform mapping

You can combine one or more of the possible transformations in a single mapping matrix. For example, you can specify 200 percent scaling and 30-degree rotation in
the same mapping. The identity mapping, which is a matrix whose elements have
the value 1.0 along the diagonal and 0.0 elsewhere, specifies no transformation. An identity mapping applied to a shape leaves it unchanged. The identity mapping is the default mapping for a transform.

One important advantage of having a mapping property separate from a shape's geometry is that you can change the visual appearance of a shape in many different ways and at many different times without ever changing the geometry of the shape itself. This minimizes the accumulation of errors, and also allows a set of identical shape geometries to result in many different appearances. QuickDraw GX provides functions with which you can easily modify the mapping of a transform object to perform translation, scaling, rotation, and skewing. See the section "Modifying the Transform Mapping" beginning on page 6-24 for more information and examples.

If you want to, however, you can also transform a shape by changing its geometry directly. Direct manipulation of shape geometry can be faster than modifying the transform object, and may be more appropriate when you want to change the fundamental nature of a shape. QuickDraw GX provides functions with which you
can directly modify the geometry of a shape object to perform translation, scaling, rotation, and skewing. See the section "Modifying Shape Geometry" beginning on page 6-26 for more information and examples.

For general information about the characteristics and capabilities of mappings, see the mathematics chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.

View Port List

The view port list property is an array of references to view port objects. The list specifies all of the view ports through which the shape associated with this transform object can be drawn. A transform object must have at least one view port reference in its view port list if any drawing is to occur. If it has more than one view port in the list, drawing occurs to all of its view ports simultaneously.

You may want to have several view ports in a list if you want the shapes associated with a transform object to display in several windows, or in different places in the same window. If you implement offscreen drawing, your transform object can reference both onscreen and offscreen view ports.

The same view port can be in the view port list more than once. For example, you may wish to draw the same shape several times, using a transfer mode that accounts for the color already on the view device. The view port list controls the order in which a shape is drawn: the shape is drawn to the first view port in the list before it is drawn to the second one in the list, and so on. You can use that information to control the order in which colors are manipulated by the transfer mode you have chosen. For information about transfer modes, see the chapter "Ink Objects" in this book.

Like transform objects, view port objects have their own clip and mapping properties that affect how a shape appears when drawn. So also do view device objects. Note that view ports do not correspond to view devices; for example, you don't need to have multiple view ports in the view port list property just because the computer has several screens. View ports and view devices are described in the chapter "View-Related Objects" in this book.

For further information and examples of manipulating the view port list of a transform object, see "Manipulating the View Port List" beginning on page 6-28.

Hit-Test Parameters

The hit-test parameters property of a transform object consists of two values that specify the criteria to be used for hit-testing shapes associated with this transform object. Hit-testing itself is introduced in the chapter "Introduction to QuickDraw GX" and described in more detail in the chapter "Shape Objects," in this book.

The hit-testing functions GXHitTestShape and GXHitTestPicture use the hit-test parameters in the transform object. The hit-testing parameters consist of

• a mask that specifies the parts of a shape that are to be tested for a hit
• a value that specifies the tolerance, or distance from any of the parts, that a hit point can be and still be considered to represent a successful hit

Shape-Parts Mask

The parts of a shape object that you can consider in hit-testing are shown in Table 6-1. They are defined in the gxShapeParts enumeration.

Table 6-1 Shape parts for hit-testing, from the gxShapeParts enumeration (Continued)

Constant	Value	Explanation
gxNoPart	0	Not in any part of the shape. This value is returned by a hit-testing function if no shape part was successfully hit.
gxBoundsPart	0x0001	Anywhere within the bounding rectangle of the shape.
gxGeometryPart	0x0002	Anywhere within the geometry of the shape. If the shape is framed, this includes just the curves or lines that make up the contours; if the shape is filled, this includes all filled areas.
gxPenPart	0x0004	Anywhere in the pen swath. For example, if this shape's style object has its gxCenterFrameStyle attribute set, this includes anywhere within half the pen width on either side of all curves or lines that make up the contours.
gxCornerPointPart	0x0008	On any geometric (on-curve) point in the shape geometry
gxControlPointPart	0x0010	On any (off-curve) control point in the shape geometry.
gxEdgePart	0x0020	On the edge of the geometry; along any of the curves or lines that make up the contours.
gxJoinPart	0x0040	Within the geometry of a join that is part of the shape.
gxStartCapPart	0x0080	Within the geometry of a start cap that is part of the shape.
gxEndCapPart	0x0100	Within the geometry of an end cap that is part of the shape.
gxDashPart	0x0200	Within the geometry of a dash element that is part of the shape.
gxPatternPart	0x0400	Within the geometry of a pattern element that is part of the shape.
gxGlyphBoundsPart	0x0040	(Same value as gxJoinPart.) For a typographic shape, anywhere within the bounding rectangle of an individual glyph.
gxGlyphFirstPart	0x0080	(Same value as gxStartCapPart.) For a typographic shape with horizontal text, anywhere within the left half of a glyph, including its left side bearing; for vertical text, anywhere in the top half of the glyph. "Left half" or "top half" means half the advance width: half of the distance from the left margin of the left side bearing to the right margin of the right side bearing.
gxGlyphLastPart	0x0100	(Same value as gxEndCapPart.) For a typographic shape with horizontal text, anywhere within the right half of a glyph, including its right side bearing; for vertical text, anywhere in the bottom half of the glyph. "Right half" or "bottom half" means half the advance width: half of the distance from the right margin of the right side bearing to the left margin of the left side bearing.
gxSideBearingPart	0x0200	(Same value as gxDashPart.) For a typographic shape, within a glyph side bearing.
gxAnyPart	0x07FF	Any of the above parts. You can pass this value to a hit-testing function if you want it to test for all possible shape parts.
Points, control points, contours, joins, caps, dashes, patterns, and other components of geometric shape geometries are described in the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics. The gxCenterFrameStyle attribute and other style attributes that apply to geometric shapes are described in the geometric styles chapter of Inside Macintosh: QuickDraw GX Graphics. Glyph bounding rectangles, side bearings, and advance widths are described in the introductory chapter of Inside Macintosh: QuickDraw GX Typography.

Tolerance

The tolerance is a value that describes how close the tested point must be to a shape part before that part is considered to have been hit. Tolerance is specified in the shape object's geometry space (except that style-object information is included when testing for pen, joins, caps, dashes, patterns, and typographic shapes). The tolerance is dimensionless
(it has no metric, such as inches), and can have any fixed-point value in the range of -32,767.0 to approximately 32,768.0. A tolerance of 0 means that the hit point must exactly coincide with a shape part for a successful hit.

For more information about coordinate spaces, see the chapter "View-Related Objects" in this book.

Setting Up the Parameters

Before calling GXHitTestShape or GXHitTestPicture, you set up the shape-parts mask in the transform object to specify the shape parts you are interested in testing for. Note that values specifying join, cap, and dash parts in geometric shapes are used in typographic shapes to specify various glyph parts instead. Note also that you can specify no parts or all parts in the mask. You also specify a tolerance, which should be 0 if the hit point must exactly coincide with a shape part for a successful hit. See "Setting Up Hit-Test Parameters" beginning on page 6-30 for more information and examples.

The GXHitTestShape function is described in the chapter "Shape Objects" in this book, with additional information for typographic shapes and typographic shape parts in the typographic shapes chapter of Inside Macintosh: QuickDraw GX Typography. The GXHitTestPicture function is described in the picture shapes chapter of Inside Macintosh: QuickDraw GX Graphics.